How to Configure

This guide covers how to configure the IWA application, including setting up a new application with its core settings, enabling data-level and API-level access, and configuring email notifications and user events.

---

Configure a New Application

Step 1: Open Application Management

1. Log in to IWA and navigate to Application Management from the home page.
2. On the Application Summary screen, click Create Application.
3. Choose how to create the application:
   • Manual form — fill in all fields directly.
   • Excel upload — upload a pre-configured Excel file with all application configuration data.

---

Step 2: Fill in Application Details

Complete the mandatory fields in the Application Details form:

Field	Description
Application Name	Unique name identifying the application.
Application Description	Brief description of the application's purpose.
Select Sources	Choose the identity sources (e.g., SAP BTP CIS, Azure AD).
Select Source Groups	Dependent on Sources; select the relevant source groups.
Domain	Enter a domain (e.g., @incture.com) and press Enter to add it. Multiple domains can be added.

---

Step 3: Enable Configuration Toggles

Use the toggles to enable additional configuration steps. The wizard breadcrumb updates dynamically based on what is enabled.

Email Notifications

1. Turn on the Email Notifications toggle.
2. An Email Events section appears.
3. Click Add Email Event to define event types (e.g., user provisioned, role assigned).
4. Configure the recipient, subject, and body template for each event.

info

At least one Email Event must be configured before the application can be submitted.

Data-Level Access

1. Turn on the Enable Data Level Access toggle.
2. A Data Level Access step is added to the wizard.
3. Create Data Attributes by providing an attribute name and data type.
4. Map attributes to the application so they are available when configuring role-level or user-level access rules.

info

At least one Data Attribute must be defined before the application can be submitted.

API-Level Access

1. Turn on the Enable API Level Access toggle.
2. An API Access configuration panel appears.
3. Add APIs by providing the API name, endpoint, and method.
4. Map the APIs to the application for use in role-level API access configuration.

info

At least one API must be defined before the application can be submitted.

User Events

1. Turn on the User Events toggle.
2. A User Events section appears.
3. Define event types (e.g., user activated, user locked).
4. Map each event type to the application.

info

At least one User Event must be defined before the application can be submitted.

Other Toggles

Toggle	Effect
Application-Level Lock	Prevents all application usage when the lock is active.
Enable User Provisioning Approval	Requires manual administrator approval before any provisioning request is fulfilled.

---

Step 4: Save or Submit

• Click Save to store the application in Draft status for further editing.
• Click Submit to activate the application immediately (status changes to Active).
• If saved as Draft, the Activate action is available from the Application Summary screen later.

---

Edit an Existing Application

1. On the Application Summary screen, locate the application row.
2. Open the Actions menu and select Edit.
3. Update any field in the Application Details form, including enabled/disabled toggles, data attributes, APIs, email events, or user events.
4. Click Save (Draft) or Submit (Active) to apply the changes.

All configuration changes are recorded in the Audit Log, including who made the change and when.

---

Configure Data-Level Access on a Role

1. Navigate to Role Management and open or create a role.
2. In the role form, select the Data-Level Access mode:
   • Disabled — no data filtering applied.
   • Simple Filtering — select straightforward filter conditions (e.g., region, country, location).
   • Advanced Access — define multi-condition, rule-based filters using complex attribute combinations.
3. The configured rules apply to all users assigned to the role when data restrictions are enabled.
4. For individual users within the role, click the Data Level Access icon next to the user entry to configure user-specific overrides.

---

Configure Source Group and Role Collection Mapping

Source Group Mapping

1. During role creation or editing, the system detects existing groups from SAP BTP CIS.
2. Select a group to map it to the role.
3. Optionally add a description and choose whether to include users from that group.

Provisioning & Deprovisioning Method

Select the method that governs how users are assigned/removed when a source group is mapped:

Method	Behaviour
SYSTEMSYNC	Provisioning and deprovisioning occur automatically based only on changes in the external source group.
ADMIN_AND_SYSTEMSYNC	User assignments can be managed through both administrator actions and automatic synchronization.

Role Collection Mapping

1. During role creation or editing, choose to connect the role to an existing SAP BTP role collection or create a new one.
2. Provide a name and optional description.
3. The IWA role is now linked to the SAP BTP role collection; users receive corresponding SAP BTP permissions automatically.

---

Configure User Reconfirmation on a Role

1. Open a role in edit mode.
2. Enable the User Reconfirmation setting.
3. Define the reconfirmation period (interval after which users must verify their continued need for the role).
4. Save or submit the role.

---

Post-Deployment Configuration & Data Migration

Seed Mandatory Application Data

After deployment, all tables will be empty. Mandatory seed data must be inserted manually using SQL scripts before the application can be used.

---

Verify or Update Application Properties

Once deployed, verify or update the following application properties:

Property	Description
idm.app.destination.path	Context path of IDM APIs.
idm.application.fieldName	Application attribute name used in IDM for application access.
idm.destination.name	IDM Destination instance name.
iwa.application.timezone	Default timezone. Set to UTC.
iwa.superAdminRoleName	Super admin role name. Super admins have access to all applications by default.
iwa.user.application.config.source	Configuration source for evaluating user application access. Set to IWA.
SPRING_PROFILES_ACTIVE	Activate the required Spring profiles.

---

Mandatory Data Insertion Order

First-time setup: Create the application manually via the IWA UI (see Configure a New Application).

Migration (Dev → QA → Production): Migrate data from the following tables in order:

CW_IWA_APPLICATION
CW_IWA_APPLICATION_API
CW_IWA_APPLICATION_EVENT_NOTIFICATION
CW_IWA_APPLICATION_MODULE
CW_IWA_CATEGORY
CW_IWA_CATEGORY_KEY_VALUE
CW_IWA_DATA_ATTRIBUTE
CW_IWA_GROUP
CW_IWA_MODULE_FEATURE
CW_IWA_ROLE
CW_IWA_ROLE_API_MAPPING
CW_IWA_ROLE_APPLICATION_MODULE_MAPPING
CW_IWA_ROLE_DATA_ATTRIBUTE_FIELD_VALUE_MAPPING
CW_IWA_ROLE_DATA_ATTRIBUTE_MAPPING
CW_IWA_ROLE_EVENT_NOTIFICATION_MAPPING
CW_IWA_ROLE_FEATURE_MAPPING
CW_IWA_ROLE_GROUP_MAPPING
CW_IWA_ROLE_MODULE_CATEGORY_MAPPING
CW_IWA_SOURCE
CW_IWA_USER                        -- Only super admin users required for initial setup
CW_IWA_USER_GROUP_ROLE_MAPPING      -- Only for required super admin role(s)

note

Migrate only application- and role-related data, as they remain constant across environments. Migrate user data only if the authentication source and user data are identical across environments.

---

Application Owner Setup

At least one application owner must be defined to perform the initial application setup. Application owners have access to all modules, features, and APIs of the assigned application by default.

• Add owners by inserting email addresses (comma-separated) into the APPLICATION_OWNER_EMAILS column of the CW_IWA_APPLICATION table via master scripts.
• Multiple owners can be configured for the same application.

---

RBAC Verification

Verify the following before go-live:

• Roles are created or migrated.
• APIs are mapped to roles.
• Modules and features are mapped to roles.
• Each user is assigned at least one role.

---

XSUAA & Authentication Check

• Verify the XSUAA instance is bound correctly to the application.
• Confirm the JWT token contains the expected attributes: email and scopes.

---

Environment Routing Validation

• In Production, no environment header is required — the application points to the production data source by default.
• In CAF multi-DB environments (DEV / QA / DEMO), the environment and consuming application are selected using HTTP request headers.

IWA UI Platform Configuration

When integrating IWA React components into a consuming application, initialise the platform configuration object:

const platformConfig = {
  env: 'dev' | 'qa' | 'demo',
  consumingApp: '<IWA App ID of consuming app>', // Optional
  platformName: 'btp' | 'azure',
  platformUrl: '<IWA backend server URL>'        // Required for Azure-deployed apps only
} as const;

Example — BTP-deployed app targeting QA schema:

const platformConfig = {
  env: 'qa',
  consumingApp: 'my-app-001',
  platformName: 'btp',
} as const;

Example — Azure-deployed app:

const platformConfig = {
  env: 'dev',
  consumingApp: 'my-app-001',
  platformName: 'azure',
  platformUrl: 'https://iwa-backend.example.com',
} as const;

Service API Header Requirements

When calling IWA backend APIs directly, include the following HTTP headers:

Header	Valid Values	Default	Description
Env	dev, qa, demo	dev	Selects the target HANA schema.
Consumingapp	IWA App ID	(all apps the user can access)	Scopes the response to a specific application.

Example — API call targeting the QA schema for a specific application:

curl -X GET https://<iwa-backend>/api/users \
  -H "Authorization: Bearer <JWT>" \
  -H "Env: qa" \
  -H "Consumingapp: my-app-001"

Example — API call with no application scope (returns all accessible apps):

curl -X GET https://<iwa-backend>/api/users \
  -H "Authorization: Bearer <JWT>" \
  -H "Env: dev"

---

Restart Application

If user-provided variables or security properties were updated after deployment, restart the application. Properties are resolved only at application startup.

---

Smoke Testing

Perform the following validations after configuration:

• Login is successful.
• Current User API returns the expected response.
• Admin screens are accessible.
• No 401 or 403 errors are present.

---

Common Issues & Resolution

Symptom	Likely Cause	Resolution
403 Forbidden	Missing role or API mapping	Verify RBAC configuration and role assignments.
No data visible	Schema mismatch or incorrect environment header	Validate HANA schemas and environment routing.
Application not starting	Missing service binding	Verify all required service bindings (XSUAA, Destination, HDI).
Authorization issues	Required role(s) not assigned to the user	Assign the correct roles via User Management.

---

Rollback Strategy

If deployment fails or the application is unstable:

1. Undeploy the MTAR: cf undeploy IWA.
2. Drop faulty schemas if required.
3. Fix the identified issue.
4. Re-deploy the MTAR: cf deploy IWA.mtar.
5. Re-run the seed scripts.

---

Go-Live Checklist

• MTAR deployed successfully.
• HANA schemas verified.
• Seed data inserted.
• Application properties verified.
• RBAC validated (roles, APIs, modules, features).
• Admin user access confirmed.
• Smoke tests passed.